Skip to main content

Create Payment Collection​

Our API helps you collect payments using different payment methods. Payment methods are available for each regions. This endpoint requires that your encrypt the JSON data before making the request. Check out our documentation here for more details on card encryption.

POST https://api.spotflow.co/api/v1/payments

Headers

authorization
String

Bearer SECRET_KEY
Include your secret key in the request header as a Bearer token for authorization. Unauthorized requests will result in a 401 HTTP status code.

content-type
String		application/json

Body Parameters for Card Payments

reference
String

Specify a unique reference ID generated by your company to identify each customer.

amount
Integer		Amount should be in the subunit of our supported currency i.e your local currency or USD.
currency
String		Select the currency for the charges. Can either be in USD or in the local currency of your collection region.
customer email
String		The customer’s email address
channel
String		The channel is Card
encryptedCard
String		This contains the encrypted card data (token) and encryption key information gotten from your dashboard. This is based on the AES-256-GCM encryption algorithm.

Sample Request Body for Card Payments

{
    "reference": "ref-{{$randomUUID}}",
    "amount": 5000,
    "currency": "NGN",
    "customer": {
        "email": "customer@email.com"
    },
    "channel": "card",
    "encryptedCard": "eudUxR9JoEw6hRmjOU9yO6PYDAOxW2CuoqRHq98eaDyyjX/ek9V6izh5dSHJ+z04K6UHswIjRvRhUvpH/ZXKsVdE/ZUT4zJ6DTWEUT+p4Dy6ZrnCMhGoFmCghkST2awAWz+ULC7fDg=="
}

Sample Response for Card Payments

200 OK 

{
    "id": "01dc7242-9357-44ea-9095-d8e91621f448",
    "reference": "ref-af1b272c-e16d-4d7b-aac3-98721ee81b1e",
    "spotflowReference": "SPF-FLW-8fb38e8fa22b4ab290e337b2afc835f5",
    "amount": 5000.00,
    "currency": "NGN",
    "channel": "card",
    "status": "pending",
    "customer": {
        "id": "3839716c-35b4-40f9-a04f-af8a399fb147",
        "email": "customer@email.com"
    },
    "rate": 1,
    "provider": "flutterwave",
    "region": "Nigeria",
    "authorization": {
        "mode": "pin"
    },
    "card": {
        "type": "Mastercard",
        "firstSix": "553188",
        "lastFour": "2950"
    }
}

Body Parameters for Bank Transfer Payments​

reference
String

Specify a unique reference ID generated by your company to identify each customer.

amount
Integer		Amount should be in the subunit of our supported currency i.e your local currency or USD.
currency
String		Select the currency for the charges. Can either be in USD or in the local currency of your collection region.
customer email
String		The customer’s email address
channel
String		The channel is bank transfer of the payment providers available on the system

Sample Request Body for Bank Transfer Payments​

{
    "reference": "ref-{{$randomUUID}}",
    "amount":10,
    "currency": "USD",
    "customer": {
        "name": "{{$randomFirstName}} {{$randomLastName}}",
        "email": "customer@email.com"
    },
    "channel": "bank_transfer"
}

Sample Response for Bank Transfer Payments​

200 OK 

{
    "id": "0e914ea4-067b-41cc-a3b6-0e0b401483bf", //payment id
    "reference": "ref-53b4a49b-6fe5-4f13-8368-90798732cc31",
    "spotflowReference": "SPF-FLW-82e3e1e5e3b348228741c8bd0a6be200",
    "amount": 10,
    "currency": "USD",
    "channel": "bank_transfer",
    "status": "provider_processed",
    "bankDetails": {
        "accountNumber": "0067100155",
        "bankName": "Mock Bank"
    },
    "customer": {
        "id": "232365a9-d956-4034-84c8-5d1d1152770c",
        "name": "Quinton Hettinger",
        "email": "customer@email.com"
    },
    "provider": "flutterwave",
    "rate": 1540.66,
}

USSD Payments​

GET https://api.spotflow.co/api/v1/banks?ussd=true

Sample Response to Get All Banks (NG available currently)

200 OK 

[
    {
        "code": "044",
        "name": "Access Bank"
    },
    {
        "code": "050",
        "name": "Ecobank"
    },
    {
        "code": "070",
        "name": "Fidelity Bank"
    },
    {
        "code": "011",
        "name": "First Bank of Nigeria"
    },
    {
        "code": "214",
        "name": "First City Monument Bank (FCMB)"
    },
    {
        "code": "058",
        "name": "Guaranty Trust Bank"
    },
    {
        "code": "030",
        "name": "Heritage Bank"
    },
    {
        "code": "082",
        "name": "Keystone Bank"
    },
    {
        "code": "303",
        "name": "Lotus Bank"
    },
    {
        "code": "105",
        "name": "Premium Trust Bank"
    },
    {
        "code": "221",
        "name": "Stanbic IBTC Bank"
    },
    {
        "code": "232",
        "name": "Sterling Bank"
    },
    {
        "code": "032",
        "name": "Union Bank"
    },
    {
        "code": "033",
        "name": "United Bank for Africa (UBA)"
    },
    {
        "code": "215",
        "name": "Unity Bank"
    },
    {
        "code": "090110",
        "name": "VFD Microfinance Bank"
    },
    {
        "code": "035",
        "name": "Wema Bank"
    },
    {
        "code": "057",
        "name": "Zenith Bank"
    }
]

Recurring Payment​

Set up recurring payments for a subscription plan using Spotflow. Check out our documentation for more details.

POST https://api.spotflow.co/api/v1/payments

Headers

authorization
String

Bearer SECRET_KEY
Include your secret key in the request header as a Bearer token for authorization. Unauthorized requests will result in a 401 HTTP status code.

content-type
String		application/json

Body Parameters for Recurring Payments via Card​

reference
String

Specify a unique reference ID generated by your company to identify each customer.

planId
String		Add the plan ID gotten when the subscription plan was created. Go to the Susbcription Plan Endpoint to know more.
amount
Integer		Amount should be in the subunit of our supported currency i.e your local currency or USD.
currency
String		Select the currency for the charges. Can either be in USD or in the local currency of your collection region.
customer email
String		The customer’s email address
channel
String		In this case, the channel is card using the available payment providers.
encryptedCard
String		This contains the encrypted card data (token) and encryption key information. This is based on the AES-256-GCM encryption algorithm.

Sample Request Body​

{
    "reference": "ref-{{$randomUUID}}",
    "planId": "5212007d-569f-4be5-a674-18ba21efb95f",
    "amount": 5000,
    "currency": "NGN",
    "customer": {
        "email": "customer@email.com"
    },
    "channel": "card",
    "encryptedCard": "tbkROEv/afX0e8W60hfDuxWvZ5ErlW2InTN5q8FpM24jaD1gdxISO3uLqWl8CSP9DXujSAMEM6M6S/V7SEbcukhAN/Toj1mTrSBmYZ7lQvfAc0009W70ErZ0wD4z6d+wIvDdOVzJZw=="
}

Sample Response​

200 OK 
{
    "id": "6cf2cfac-3919-42d8-89ec-ab73e594d225",
    "reference": "ref-592109f8-9734-49e3-8c73-711510fac8b4",
    "spotflowReference": "SPF-FLW-4146f5abadb74f6395e3625503543940",
    "amount": 5000.00,
    "currency": "NGN",
    "channel": "card",
    "status": "pending",
    "customer": {
        "id": "3839716c-35b4-40f9-a04f-af8a399fb147",
        "email": "customer@email.com"
    },
    "rate": 1,
    "provider": "flutterwave",
    "region": "Nigeria",
    "authorization": {
        "mode": "pin"
    },
    "card": {
        "type": "Mastercard",
        "firstSix": "553188",
        "lastFour": "2950"
    }
}

Ensure you authorize the payments with our Authorize Payment Endpoint.